home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Disc to the Future 2
/
Disc to the Future Part II Programmer's Reference (Wayzata Technology)(6013)(1992).bin
/
MAC
/
THINKC
/
TCL1
/
CDICTION
/
CDICTION.DOC
< prev
next >
Wrap
Text File
|
1990-01-12
|
4KB
|
125 lines
Documentation for CDictionary
-----------------------------
A dictionary is a set of Associations. An association is a set of
key/value pairs. You use a dictionary to store and retrieve values
by their keys. Keys are always unique. The typical implementation allows
you to rapidly retrieve values or find out if the dictionary contains
a particular key or value.
This dictionary is implemented as a hash table with linear probing. This
is a simple implementation with pretty low overhead but performs less
well than other algorithms, particularly in regard to unsuccessful lookups.
Key size is determined when the dictionary is created; within a given instance
all keys must be the same size. Note, however that a key could be a handle or an
object. In this case, the data the keys reference can be variable size. Values
are always 4 bytes. Although values are declared as CObject, in most cases the
dictionary makes no interpretation of the data so it could be a handle, pointer,
or whatever. The exceptions to this are the DisposeItems, DisposeAll methods.
These assume the values are valid objects.
To use a dictionary, you need to provide two functions (not methods!). These
are:
Mapping function - This is a function declared as:
unsigned long MyMapProc( void *key)
This function takes a pointer to a key and returns an unsigned
long integer. It maps the values in the domain of your key to
integers. For example, if your keys are strings, you might
add up all the characters in the string. The map function
doesn't need to produce values constrained to the table
size. This is handled by the dictionary.
Hash tables live or die by their hash functions. The more
evenly the hash values are distributed, the better the
hash table will perform. You should attempt to take the characteristics
of your data into account when creating the map function.
Comparison function - This function is declared as:
Boolean MyCompareProc( void *key1, void *key2);
This function takes pointers to two keys and returns true
if they are equal and fals if they are not.
Summary of CDictionary Methods
------------------------------
virtual Boolean IDictionary( Int16 keySize, MapProc map, CompareProc compare,
Int32 initialSize);
Initializes a dictionary. keySize is the size in bytes of the keys.
map and compare are pointers to your map and comparison functions.
initialSize is the initial size of the dictionary. You may pass 0
to get the default minimum size. FALSE (noErr) is returned if
initialization was successful.
virtual void Dispose( void);
Dispose of the dictionary but not the contents.
virtual void DisposeAll( void);
Disposes of the dictionary and all the contents by calling
DisposeItems.
virtual void DisposeItems( void);
Disposes of the contents of the dictionary but not the dictionary
itself, so when DisposeItems returns the dictionary is empty
but still usable. A Dispose() message is sent to each value of
each association.
virtual void Add( void *key, CObject *value);
Adds an association to the dictionary. If key already exists then
the value is replaced with the new value. No dispose message is
sent to the old value.
virtual void AddAll( CDictionary *aDictionary);
Adds the contents of an existing dictionary to the dictionary.
virtual void Remove( void *key);
Removes the association for key if it is present.
virtual CObject *Lookup( void *key);
Returns the value associated with key, or 0 (NIL, NULL) if
not present.
virtual Boolean IncludesKey( void *key);
Returns true if key is in the dictionary, else false.
virtual Boolean IncludesValue( CObject *anObject);
Returns true if anObject is in the dictionary, else false.
Note that this requires a linear search of the dictionary.
virtual void DoForEach( DictIterator actionProc);
Iterates over all the dictionary entries and calls actionProc
for each one. actionProc should be declared as:
void actionProc( tAssociationPtr anAssoc);
virtual void DoForEach1( DictIterator1 actionProc, Int32 aParam);
Iterates over all the dictionary entries and calls actionProc
for each one. actionProc should be declared as:
void actionProc( tAssociationPtr anAssoc, Int32 aParam);
virtual CObject *Copy( void);
Returns a copy of the dictionary